---
title: gluestack-ui Button Component | Installation, Usage, and API

description: A button component is a graphical user interface element that enables users to act by clicking or tapping. It can be customized in size, shape, color, and behavior to fit the design of the application or website.

pageTitle: Button

pageDescription: A button component is a graphical user interface element that enables users to act by clicking or tapping. It can be customized in size, shape, color, and behavior to fit the design of the application or website.

showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="common/components/Forms/Button" />

import { Button, ButtonText, ButtonIcon } from './Button';

import { transformedCode } from '../../utils';
import { CodePreview } from '@gluestack/design-system';

import Wrapper from '../../core-components/nativewind/Wrapper';
import { CollapsibleCode } from '@gluestack/design-system';

This is an illustration of **Button** component.

<>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={true}
    metaData={{
      code: `
        <Button {...props}>
          <ButtonText>Hello World!</ButtonText>
        </Button>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Button, ButtonText, ButtonIcon, Wrapper },
      argsType: {
        size: {
          control: 'select',
          options: ['xs', 'sm', 'md', 'lg'],
          default: 'md',
        },
        variant: {
          control: 'select',
          options: ['solid', 'outline', 'link'],
          default: 'solid',
        },
        action: {
          control: 'select',
          options: ['primary', 'secondary', 'positive', 'negative'],
          default: 'primary',
        },
      },
    }}
  />
</>

<br />

## Installation

### Step 1: Install the following dependencies:

```bash

npm install @gluestack-ui/button

```

### Step 2: Copy and paste the following code into your project.

<CollapsibleCode>

```jsx 
%%-- File: core-components/nativewind/button/index.tsx --%% 
```

</CollapsibleCode>

### Step 3: Update the import paths to match your project setup.

## API Reference

To use this component in your project, include the following import statement in your file.

```jsx
import {
  Button,
  ButtonText,
  ButtonSpinner,
  ButtonIcon,
  ButtonGroup,
} from '@/components/ui/button';
```

```jsx
export default () => (
  <ButtonGroup>
    <Button>
      <ButtonText />
      <ButtonSpinner />
      <ButtonIcon />
    </Button>
  </ButtonGroup>
);
```

### Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

#### Button

Contains all button related layout style props and actions. It inherits all the properties of React Native's [Pressable](https://reactnative.dev/docs/pressable) component.

<Wrapper>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isHovered</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To manually set hover to the button.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isPressed</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To manually set pressable state to the button.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isFocused</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To manually set focused state to the button.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isDisabled</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To manually set disable to the button.`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</Wrapper>

#### ButtonText

Contains all text related layout style props and actions. It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

#### ButtonGroup

Contains all group related layout style props and actions. It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

<Wrapper>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>flexDirection</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              'row' | 'column' | 'row-reverse' | 'column-reverse'
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>'row'</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              Set the direction of Button group to vertical or horizontal
            </Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isDisabled</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, this will disable all the buttons in a ButtonGroup.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isAttached</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When attached, all buttons will be attached to each other.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>reversed</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To reverse the order of components.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>space</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>string</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>md</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              It sets the space between different buttons.
            </Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</Wrapper>

#### ButtonSpinner

Contains all spinner related layout style props and actions.
It inherits all the properties of React Native's [ActivityIndicator](https://reactnative.dev/docs/activityindicator) component.

#### ButtonIcon

Contains all Icon related layout style props and actions. It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

### Features

- Keyboard support for actions.
- Support for hover, focus and active states.
- Option to add your styles or use the default styles.

### Accessibility

We have outlined the various features that ensure the Button component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the [WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).

#### Keyboard

- `Tab`: Moves focus to the next focusable element.
- `Shift + Tab`: Moves focus to the previous focusable element.
- `Enter`: Triggers the button's action.

### Screen Reader

- VoiceOver: When the button is focused, the screen reader will announce the button's label and its current state.

### Focus Management

- The `onFocus` and `onBlur` props to manage focus states and provide visual cues to users. This is especially important for users who rely on keyboard navigation.

## Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

#### Button with Loading State

A loading button is a type of button component that provides visual feedback to the user during an action that takes some time to complete. It typically displays an animated loading icon or spinner indicating the action is in progress.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <Button isDisabled={true} bg='$darkBlue600' p='$3'>
          <ButtonSpinner mr='$1'/>
          <ButtonText fontWeight='$medium' fontSize='$sm'>Please wait...</ButtonText>
        </Button>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Button, ButtonText, ButtonIcon, Wrapper, ButtonSpinner },
      argsType: {},
    }}
  />
</Wrapper>

#### Icon Button

A button with an icon integrates a visual symbol within the button component, enhancing its appearance and providing a recognizable and intuitive representation of its associated action or functionality.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <Button borderRadius='$full' size='lg' p='$3.5' bg='$indigo600' borderColor='$indigo600' >
          {\/* EditIcon is imported from 'lucide-react-native' *\/}
          <ButtonIcon as={EditIcon}/>
        </Button>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Button, ButtonText, ButtonIcon, Wrapper, Icon, EditIcon },
      argsType: {},
    }}
  />
</Wrapper>

#### Link Button

A button with a link combines the interactive behavior of a button component with the ability to navigate to a specified URL, providing a clickable element for users to access external resources or internal pages.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <Button variant='link'>
          <ButtonText fontWeight='$medium' fontSize='$sm' color='$textLight900' $dark-color="$textDark300">
            Back to top
          </ButtonText>
          <ButtonIcon as={ArrowUpIcon} h='$3' w='$3' color='$backgroundLight900' ml='$1' $dark-color="$backgroundDark300"/>
        </Button>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Button, ButtonText, ButtonIcon, Wrapper, Icon, ArrowUpIcon },
      argsType: {},
    }}
  />
</Wrapper>

#### Button Group in a Card

A button group within a card component incorporates multiple button components, providing a cohesive and organized interface for selecting various actions or options within the context of the card.

<Wrapper>
  <CodePreview
    _rendererWrapper={{ py: '$8' }}
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <HStack  p='$12'  alignItems='center'  borderColor='$backgroundLight300'
          borderWidth={1} borderRadius="$lg" $dark-borderColor="$backgroundDark700">
          <Box maxWidth='$64' mr='$9'>
            <Heading mb='$1.5' >
              Was this page helpful?
            </Heading>
            <Text fontSize='$sm' >
              We use this feedback to improve the quality of our documentation.
            </Text>
          </Box>
          <ButtonGroup space='md'>
            <Button variant='outline' py='$2.5' action="secondary">
              <ButtonText  fontSize='$sm' fontWeight='$medium'
              >
                No
              </ButtonText>
            </Button>
            <Button
              variant='solid'
              bg='$success700'
              borderColor='$success700'
              $hover-bg='$success800'
              $active-bg='$success700'
            >
              <ButtonText  fontSize='$sm' fontWeight='$medium'>
                Yes
              </ButtonText>
            </Button>
          </ButtonGroup>
        </HStack>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Button,
        ButtonText,
        ButtonIcon,
        ButtonGroup,
        Wrapper,
        Box,
        Heading,
        Text,
        HStack,
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Button With Icon

The icon component incorporates a button component, combining visual representation with interactive functionality for seamless user interaction.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <Box>
          <Button>
          <ButtonIcon as={InfoIcon} mr="$2"/>
            <ButtonText>Left Icon</ButtonText>
          </Button>
          <Button variant="solid" mt="$2">
          <ButtonText>Right Icon</ButtonText>
              <ButtonIcon as={AddIcon} ml="$2"/>
          </Button>
        </Box>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Button,
        ButtonText,
        ButtonIcon,
        Wrapper,
        Icon,
        InfoIcon,
        AddIcon,
        Box,
      },
      argsType: {},
    }}
/>

</Wrapper>

#### Button with Full Width

The button with full width component utilizes a button component, expanding its width to occupy the entire available space, creating a visually prominent and easily accessible interface element.

<Wrapper>
  <CodePreview
    _rendererWrapper={{ py: '$8' }}
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <Center>
          <Box p='$5' maxWidth='$96' borderWidth='$1' borderColor='$backgroundLight300' borderRadius='$lg' $dark-borderColor="$backgroundDark700">
            <VStack space='xs' pb='$4'>
              <Heading lineHeight={30}>
                Set new password
              </Heading>
              <Text fontSize='$sm'>
                Almost done. Enter your new password and you are all set.
              </Text>
            </VStack>
            <VStack space='xl' py='$2'>
              <Input>
                <InputField
                  py='$2'
                  placeholder="New password"
                />
              </Input>
              <Input>
                <InputField
                  py='$2'
                  placeholder="Confirm new password"
                />
              </Input>
            </VStack>
            <VStack space='lg' pt='$4'>
              <Button
                size='sm'
              >
                <ButtonText>
                  Submit
                </ButtonText>
              </Button>
              <Box flexDirection='row'>
                <Button variant='link' p='$0' size='sm'>
                  {\/* ArrowLeftIcon is imported from 'lucide-react-native' *\/}
                  <Icon
                    size='md'
                    mr='$1'
                    as={ArrowLeftIcon}
                  />
                  <ButtonText
                  >
                    Back to login
                  </ButtonText>
                </Button>
              </Box>
            </VStack>
          </Box>
        </Center>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Button,
        ButtonText,
        ButtonIcon,
        Wrapper,
        VStack,
        Box,
        Heading,
        Text,
        Input,
        InputField,
        Icon,
        Center,
        ArrowLeftIcon,
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Custom Button

The custom button component leverages the functionality of a button component while offering additional customization options to tailor its appearance and behavior according to specific design requirements.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <ButtonGroup isAttached>
          <Button variant="outline" size='xs' borderColor='$backgroundLight300' borderRightWidth='$0' $dark-borderColor="$backgroundDark700">
            <ButtonText color='$textLight900' $dark-color="$textDark300">
              Export
            </ButtonText>
          </Button>
          <Button variant="outline" size='xs' borderColor='$backgroundLight300' $dark-borderColor="$backgroundDark70">
            <ButtonIcon as={ThreeDotsIcon} color="$textLight900" $dark-color="$textDark300"/>
          </Button>
        </ButtonGroup>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Button,
        ButtonText,
        ButtonIcon,
        ButtonGroup,
        Wrapper,
        ThreeDotsIcon,
      },
      argsType: {},
    }}
  />
</Wrapper>

## gluestack-style

Step 1: Install the following dependencies:

```bash

npm install @gluestack-ui/button
npm install @gluestack-style/react

```

Step 2: Copy and paste the following code into your project.

<CollapsibleCode>

```jsx 
  %%-- File: core-components/themed/button/index.tsx --%% 
  ```

</CollapsibleCode>

Step 3: Update the import paths to match your project setup.

# Usage

```jsx
import { Button } from '@/components/ui/ui/button';
```

```jsx
<Button variant="outline">
  <ButtonText>Button</ButtonText>
</Button>
```
